ODPersistentObject

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODPersistentObject

Superclasses
ODRefCntObject --> ODObject
Subclasses
ODFrame, ODLink, ODLinkSource, and ODPart

An object of the ODPersistentObject class implements the protocol for saving and restoring objects to persistent storage.

Description
Certain objects created in one OpenDoc session can be saved to persistent storage; in a later session, the same objects can be re-created from their stored data. Similarly, an object that is not currently being used can be saved to persistent storage to free space in memory; if the object is needed later in the same session, it can be re-created from its stored data. An object whose state can be saved to persistent storage is called a persistent object.
The ODPersistentObject class is the abstract superclass for all OpenDoc classes whose objects need to be saved persistently. You should not create immediate subclasses or instances of ODPersistentObject itself. Three of its subclasses are concrete classes: ODFrame, ODLink, and ODLinkSource. You can create instances of those classes, but you should not create subclasses of them. The ODPersistentObject class has a fourth subclass, ODPart, which is an abstract class. To develop a part editor, you need to create a subclass of ODPart. The persistent objects that can be saved and re-created from storage are frames, links, link sources, and parts.
Each persistent object has an associated storage unit in which it can store its data persistently. Within each draft in a particular session, the storage unit is given a unique identifier (ID) that designates both the storage unit itself and the persistent object whose data it contains. This ID is not part of the object's persistent data but is valid only for the duration of the session.
The process of storing a persistent object's data is called externalizing the object. When a persistent object writes itself to storage, it writes into its storage unit whatever information is necessary to restore it to its current state. When a stored persistent object is re-created, it initializes itself to its previous state by reading the data it stored when it was last written.
A persistent object can also be cloned, that is, the object and all additional objects that it references can be copied. Typically, an object is cloned whenever its data must be transferred, for example, when it is copied to the clipboard.
For more information about storage units, see the ODStorageUnit class description (page 664). For more information about cloning, see the chapter on data transfer in the OpenDoc Programmer's Guide for the MacOS. For more information about the different kinds of persistent objects, see the descriptions for the classes ODFrame (page 294), ODLink (page 348), ODLinkSource (page 371), and ODPart (page 459).

Methods
This section presents summary descriptions of the ODPersistentObject methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Initializing and Releasing

InitPersistentObject

Initializes this newly created persistent object.
InitPersistentObjectFromStorage
Initializes this re-created persistent object from its stored data.
ReleaseAll
Releases all transitory references from this persistent object to other reference-counted objects.
Accessing

GetID
Returns the unique ID of this persistent object for the current draft in the current session.
GetStorageUnit
Returns a reference to the storage unit in which this persistent object stores its data.
Writing

Externalize
Stores the data needed to restore this persistent object to its current state.
CloneInto
Clones this persistent object by copying its data into the specified storage unit.

Methods
CloneInto
Externalize
GetID
GetStorageUnit
InitPersistentObject
InitPersistentObjectFromStorage
ReleaseAll